home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource4 / 222_01 / clib.doc < prev    next >
Text File  |  1979-12-31  |  15KB  |  503 lines
  1.  
  2.             CLIB.DOC
  3.  
  4.                by
  5.  
  6.              F. A. Scacchitti
  7.              25 Glenview Lane
  8.              Rochester, NY 14609
  9.                3 - 30 - 86
  10.  
  11. This  'C' Library contains most of the functions described in  J. 
  12. E.  Hendrix's  "The Small-C Handbook".  These functions are  also 
  13. described in the May 1984 Dr.  Dobb's Journal.  My intent,  as is 
  14. his,   is  to  provide  a  complete  standard  library  following 
  15. specications  described  in "The C  Programming  Language".  This 
  16. library  is  a  combination of modules  obtained  from  Hendrix's 
  17. library,  a  modified  public domain runtime library and  modules 
  18. written  by  myself.  The  following  source  files  contain  the 
  19. functions described in this document:
  20.  
  21.     ABORT   .MAC    ABS     .C    ATOI    .C
  22.         ATOIB   .C      AVAIL   .C      BDOS    .MAC
  23.     CALL1   .MAC    CALL2   .MAC    CALL3   .MAC
  24.     CALL4   .MAC    CALL5.  .MAC    CALLOC  .C
  25.         CLEARERR.C    CPMDISK .MAC    CPMIO   .MAC
  26.     CSEEK   .C      CTELL   .C    CTELLC  .C
  27.     DELAY   .MAC    DOLDDR  .MAC    DOLDIR  .MAC
  28.     DTOI    .C      FEOF    .C    FERROR  .C
  29.         FFLUSH  .C      FGETC   .MAC    FGETS   .MAC
  30.         FILELIB .C      FPRINTF .C      FPUTC   .MAC
  31.         FPUTS   .MAC    FREAD   .C      FREBUF  .C
  32.         FREE    .C      FREEIO  .MAC    FSCANF  .C
  33.         FWRITE  .C      GETCHAR .C      GETCHX  .C      
  34.     GETS    .MAC    GRABIO  .MAC    GRABUF  .C      
  35.     INP     .MAC    ISALNUM .C      ISALPHA .C
  36.         ISASCII .C      ISATTY  .C      ISCNTRL .C
  37.         ISDIGIT .C      ISGRAPH .C      ISLOWER .C
  38.         ISPRINT .C      ISPUNCT .C      ISSPACE .C
  39.         ISUPPER .C      ISXDIGIT.C      ITOA    .C
  40.         ITOAB   .C      ITOD    .C      ITOO    .C
  41.         ITOU    .C      ITOX    .C      LEFT    .C
  42.         LEXCMP  .C      LIBID   .C      MALLOC  .C
  43.         MAX     .C      MIN     .C      OTOI    .C
  44.         OUTP    .MAC    PAD     .C      POLL    .C
  45.         PRNTF   .C      PUTCHAR .C      PUTLIST .MAC
  46.         PUTS    .C      READ    .C      RENAME  .C
  47.         REVERSE .C      REWIND  .C      SIGN    .C
  48.         STRCAT  .C      STRCHR  .C      STRCMP  .C
  49.         STRCPY  .C      STRLEN  .C      STRNCAT .C
  50.         STRNCMP .C      STRNCPY .C      STRRCHR .C
  51.         TOASCII .C      TOLOWER .C      TOPOFMEM.MAC
  52.         TOUPPER .C      UALLOC  .C      ULINK   .C
  53.         UNGETC  .C      UNLINK  .MAC    UTOI    .C
  54.         WRITE   .C      XTOI    .C      ZZBUF   .MAC    
  55.         ZZFIO   .MAC
  56. Rather  than  trying to provide a Unix-like environment (and  the 
  57. resulting  overhead),  I've attempted to put a  package  together 
  58. which  is  more conducive to CP/M.  This Library is  designed  to 
  59. produce  minimum  size files while retaining the flavor  of  'C'. 
  60. Many  of  the  functions are written in assembler  and,  as  time 
  61. permits,  more  functions  will be optimized for  both  size  and 
  62. speed.  Most functions contained in this library are useable with 
  63. any CP/M 80 system,  however,  many of the I/O functions interact 
  64. with each other as well as the runtime routines.  Anyone adapting 
  65. any  portions of this library should evaluate the source code  of 
  66. the particular module(s) in question. As with all libraries, its' 
  67. value  manifests itself when used with a linking-loader that  has 
  68. search capabilities. (eg. Microsofts M80/L80/LIB80 package)
  69.  
  70.  
  71.  
  72. FEATURES OF THE LIBRARY
  73.  
  74. 104 functions (7 aliases) are available,  including most standard 
  75. 'C' functions.
  76.  
  77. Smaller  program  size than most - minimum program  size  is  256 
  78. bytes. This would be the result of the following 'C' code.
  79.  
  80.      #include <stdio.h>
  81.  
  82.      main() {
  83.      }
  84.  
  85. Argc and argv are handled by the runtime module and always passed 
  86. to the user program. A maximum of 24 arguments may be passed with 
  87. 23 available to the user.
  88.  
  89. Files may be opened in read,  write or append  modes.  Read/write 
  90. (+) modes are not supported.
  91.  
  92. All I/O buffers are allocated outside program space including:
  93.  
  94.      1    128 byte default disk I/O buffer
  95.      8    1 K byte file buffers (available for general use)
  96.  
  97.      The  default disk I/O buffer is set by the runtime module to 
  98.      preserve the contents of the run string residing at the CP/M 
  99.      default  buffer.   The  standard  default  buffer  (80h)  is 
  100.      restored at program completion.
  101.  
  102.      The   8  file  buffers  are  automatically   allocated   and 
  103.      deallocated  by  the  file handling routines  and  the  user 
  104.      needn't worry about sequence. However, these buffers are not 
  105.      restricted  to  file  I/O.  They may be  allocated  via  the      
  106.      grabuf() function and deallocated via frebuf(). Caution must      
  107.      be  used  to insure that any use of these buffers  does  not 
  108.      exceed  the 1 K-byte limit.  The results of failing to  stay 
  109.      within the limits is unpredictable.
  110.  
  111. Sequential    dynamic   memory   allocation/deallocation   scheme 
  112. (calloc,malloc,  and  free) starts at the end of the last  buffer 
  113. and  ends at the stack.  The user must maintain the integrity  of 
  114. this  area.  If  a  buffer is set free below one that  should  be 
  115. maintained,  the  schema  will  indicate  all  memory  above  and 
  116. including the released buffer is available.  Allocating and using 
  117. another buffer at this point may undesirably wipe out data  which 
  118. should have been maintained.
  119.  
  120. Optionally  eliminate  the  warm  boot  that  occurs  on  program 
  121. termination.  This  is accomplished in the following manner:
  122.  
  123.      Defining  the global ZZZCCP = 0 places the stack at the base 
  124.      of the BDOS and returns via warm boot. (jmp 0) 
  125.  
  126.      Defining the global ZZZCCP = 1 places the stack at the  base 
  127.      of the CCP and returns to the CCP.
  128.  
  129.      ZZZCCP may be generated as a compiler function via a switch, 
  130.      or added as the following inline code to a program or header 
  131.      file.
  132.                     #asm
  133.                     zzzccp:: db 1  
  134.                     #endasm
  135.  
  136.      If  left undefined it will default to warm boot.  The linker 
  137.      will indicate it as undefined, with no consequence. 
  138.  
  139. CP/M  integrity is maintained by the runtime module and  restored 
  140. at  program completion.  Also,  all open files  are  closed,  but 
  141. buffers are NOT flushed.
  142.  
  143. prntf() is a special version of printf which only supports the d, 
  144. c,  and s specifications. Field length specifiers (when used) are 
  145. limited to a size of 9 and field separator specifications  aren't 
  146. allowed and should not be used. This module occupies 828 bytes of 
  147. code space.
  148.  
  149. getchx()  is  a  special version of getchar() which  uses  direct 
  150. console input rather than the standard console input. It does not 
  151. reflect  characters  to  the  screen or  trap  the  CP/M  control 
  152. characters.
  153.  
  154. putdisp()  is  an  alias  for putchar and may be  used  when  the 
  155. redirectable  library  (RDTL.REL)  is  linked  to  force  console 
  156. display.
  157.  
  158. getkbd() is an alias for getchar and may be  used  when  the 
  159. redirectable  library  (RDTL.REL)  is  linked  to  force  console 
  160. display.
  161.  
  162. grabuf()  and  frebuf() allow the user access to a self  managing 
  163. memory allocation scheme.  Each buffer returned by grabuf() is 1K 
  164. bytes of memory and should not be exceeded.  Although this  isn't 
  165. standard,  it  does provide a somewhat bomb resistant (not proof) 
  166. memory alloc./dealloc. schema along with the standards.
  167.  
  168.  
  169.  
  170.  
  171. FUNCTIONS IN THE LIBRARY 
  172.  
  173. Only  the  functions not described in  J.  E.  Hendrix's  Small-C 
  174. Manual, or those that differ from his, will be described.
  175.  
  176. abort(code) 
  177.      exits  the  program  displaying the  "Aborted"  message  and 
  178.      optional  code  passed by the user.  If no code is passed  a 
  179.      default code of control g (bell) is used.
  180.  
  181. abs(nbr) int nbr
  182.  
  183. atoi(str) char *str
  184.      
  185. atoib(str,base) char *str; int base;
  186.  
  187. avail(abort) int abort;
  188.  
  189. bdos(fn,data) int fn, data;
  190.      standard CP/M bdos call fn is the function code and data  is 
  191.      the  setting of the de register.  Returns whatever the  call 
  192.      places in the accumulator.
  193.  
  194. calloc(nbr,sz) int nbr, sz;
  195.  
  196. cfree(addr) char *addr;
  197.  
  198. clearerr(fd) int fd;
  199.  
  200. cpm(fn,data) same as bdos(fn,data)
  201.  
  202. cpmdisk(nbr) int nbr;
  203.      log in disk number nbr.
  204.  
  205. cseek(fd,offset,mode)
  206.  
  207. ctell(fd) int fd;
  208.  
  209. ctellc(fd) int fd;
  210.  
  211. delay(n) int n;
  212.      delay  for  n  milliseconds, based on a  4  Mhz  clock  (250      
  213.      nanosecond cycle time).
  214.  
  215. delete(name) char *name;
  216.  
  217. dolddr(source, destination, n) int source, destination, n;
  218.      perform z80 lddr instruction.
  219.  
  220. doldir(source, destination, n) int source, destination, n;
  221.      perform z80 ldir instruction
  222.  
  223. dtoi(decstr, nbr) char *decstr; int nbr;
  224.  
  225.  
  226. exit(code) exit();
  227.      exits program and returns to CP/M
  228.  
  229. fcb(fd,name) char *name; int fd;
  230.      construct a file fcb on file name at location fd. 
  231.      (located in filelib module)
  232.  
  233. fclose(fd) int fd;
  234.      (located in file lib module)
  235.  
  236. feof(fd) int fd;
  237.  
  238. ferror(fd) int fd;
  239.  
  240. fflush(fd) int fd;
  241.  
  242. fgetc(fd) int fd;
  243.  
  244. fgets(str, sz, fd) char *str; int sz, fd;
  245.  
  246. fopen(filename, mode) char *name, mode;
  247.      (located in filelib module - only r, w, and a modes )
  248.  
  249. fprintf(fd, format[, arg1, ar2,...]) int fd; char *format;
  250.  
  251. fputc(c, fd) char c; int fd;
  252.  
  253. fputs(str, fd) char *str; int fd;
  254.  
  255. fread(buffer, sz, n, fd) char *buffer; int fd, n, sz;
  256.  
  257. frebuf(buff) int buff;
  258.      free  the  buffer  buff allocated by grabuf()  and  make  it 
  259.      available for use.
  260.  
  261. free(addr) same as cfree(addr)
  262.  
  263. freeio(fd) int fd;
  264.      free  the  file structure allocated by grabio() and make  it 
  265.      available for use.
  266.  
  267. fscanf(fd, format, arg, arg, . . . ) 
  268.  
  269. fwrite(buff, sz, n, fd) char *buf; int sz, n, fd;
  270.  
  271. getc(fd) same as fgetc(fd)
  272.  
  273. getchar()
  274.  
  275. getchx()
  276.      is a special version of getchar() which uses direct  console 
  277.      input  rather than the standard console input.  It does  not 
  278.      reflect  characters  to the screen or trap the CP/M  control 
  279.      characters.
  280.  
  281. getkbd() same as getchar
  282.  
  283. gets(str) char *str;
  284.  
  285. grabio()
  286.      returns  the  address  of  the  first  available  file   I/O 
  287.      structure. If none is available NULL is returned.
  288.  
  289. grabuf()
  290.      returns  the  address of the first available buffer  in  the 
  291.      file I/O structure. If none is available NULL is returned.
  292.  
  293. inp(nbr) int nbr;
  294.      returns the value read in at port nbr
  295.  
  296. isalnum(c) char c;
  297.  
  298. isalpha(c) char c;
  299.  
  300. isascii(c) char c;
  301.  
  302. isatty(fd) int fd;
  303.  
  304. iscntrl(c) char c;
  305.  
  306. isdigit(c) char c;
  307.  
  308. isgraph(c) char c;
  309.  
  310. islower(c) char c;
  311.  
  312. isprint(c) char c;
  313.  
  314. ispunct(c) char c;
  315.  
  316. isspace(c) char c;
  317.  
  318. isupper(c) char c;
  319.  
  320. isxdigit(c) char c;
  321.  
  322. itoa(nbr, str) int nbr; char *str;
  323.  
  324. itoab(nbr, str, base) int nbr, base; char *str;
  325.  
  326. itod(nbr, str, sz) int nbr,sz; char *str;
  327.  
  328. itoo(nbr,str,sz) int nbr,sz; char *str;
  329.  
  330. itou(nbr,str,sz) int nbr,sz; char *str;
  331.  
  332. itox(nbr,str,sz) int nbr,sz; char *str;
  333.  
  334. left(str) char *str;
  335.  
  336. lexcmp(str1, str2) char *str1, *str2;
  337.  
  338. libid()
  339.      displays the date and originator of this library
  340.  
  341. malloc(sz) int sz;
  342.  
  343. max(a, b) int a, b;
  344.      returns the greater of a or b
  345.  
  346. min(a, b) int a, b;
  347.      returns the lesser of a or b
  348.  
  349. otoi(str,nbr) char *str; int nbr;
  350.  
  351. outp(nbr,data) int nbr, data;
  352.      transmits data out of port nbr.
  353.  
  354. pad(dest, ch, n) char *dest, *n; int ch;
  355.  
  356. poll(pause) int pause;
  357.  
  358. printf(format[,arg1,arg2,...])
  359.  
  360. prntf(format[,arg1,arg2,...])
  361.      is a special version of printf which only supports the d, c, 
  362.      and  s specifications.  Field length specifiers (when  used) 
  363.      are   limited   to  a  size  of  9   and   field   separator 
  364.      specifications  aren't allowed and should not be used.
  365.  
  366. putc(c, fd)  same as fputc(c, fd)
  367.  
  368. putchar(c) char c;
  369.  
  370. putdisp(c) char c; same as putchar
  371.  
  372. putlist(c) char c;
  373.      outputs character c to the list device.
  374.  
  375. puts(str) char *str;
  376.  
  377. read(fd, buff, n) int fd, n; char *buff
  378.  
  379. rename(old,new) char *old, *new;
  380.  
  381. reverse(str) char *str;
  382.  
  383. rewind(fd) int fd;
  384.  
  385. scanf(format, arg1, arg2, . . .)
  386.  
  387. sign(nbr) int nbr;
  388.  
  389. strcat(dest, sour) char *dest, *sour;
  390.  
  391. strchr(str, c) char *str, c;
  392.  
  393. strcmp(str1, str2) char *str1, *str2;
  394.  
  395. strcpy(dest, sour) char *dest, *sour;
  396.  
  397. strlen(str) char *str;
  398.  
  399. strncat(dest, sour, n) char *dest, *sour; int n;
  400.  
  401. strncmp(str1, str2, n) char *str1, *str2; int n;
  402.  
  403. strncpy(dest, sour, n) char *dest, *sour; int n;
  404.  
  405. strrchr(str, c) char *str, c;
  406.  
  407. toascii(c) char c;
  408.  
  409. tolower(c) char c;
  410.  
  411. topofmem()
  412.      returns base of system bdos
  413.  
  414. toupper(c) char c;
  415.  
  416. ualloc(n, clear) char *n; int clear;
  417.  
  418. ungetc(c, fd) char c; int fd;
  419.  
  420. unlink(name) same as delete(name)
  421.  
  422. utoi(str, nbr) char *str; int nbr;
  423.  
  424. write(fd,buffer,n) int fd, n; char *buffer;
  425.  
  426. xtoi()(str, nbr) char *str; int nbr;
  427.  
  428.  
  429.  
  430. LIBRARY STRUCTURE
  431.  
  432.  
  433.  
  434. The  clib.rel  Small-C system library modules are loaded  in  the 
  435. following sequence to avoid backward referencing by L80:
  436.  
  437. ULINK**        LIBID*        UNGETC        RENAME    
  438. FREAD        READ        FWRITE        WRITE
  439. FFLUSH        REWIND        CSEEK        CTELL    
  440. CTELLC        FILELIB        GRABUF*        GRABIO*
  441. FREBUF*        FREEIO*        FPRINTF        FSCANF
  442. PRNTF*        FPUTS        FGETS        GETS
  443. PUTS        FPUTC        FGETC        PUTCHAR
  444. GETCHAR        GETCHX*         CPMIO*        CPMDISK*
  445. PUTLIST*    CALLOC          MALLOC        UALLOC*
  446. AVAIL*        FREE        POLL*        ABS
  447. ATOI        ATOIB           DTOI        ISALNUM
  448. ISALPHA        ISASCII         ISATTY        ISCNTRL
  449. ISDIGIT        ISGRAPH         ISLOWER        ISPRINT
  450. ISPUNCT        ISSPACE         ISUPPER        ISXDIGIT
  451. ITOA        ITOAB           ITOD        ITOO
  452. ITOU        ITOX            LEFT        LEXCMP
  453. OTOI        REVERSE         SIGN        STRCAT
  454. STRCHR        STRCMP          STRCPY        STRLEN
  455. STRNCAT        STRNCMP         STRNCPY        STRRCHR
  456. TOASCII        TOLOWER         TOUPPER        UTOI
  457. XTOI        PAD             FEOF        FERROR
  458. CLEARERR    DELAY*        DOLDDR*        DOLDIR*
  459. INP*            OUTP*        TOPOFMEM*    UNLINK
  460. MIN*        MAX*        CALL1**        CALL2**
  461. CALL3**        CALL4**        CALL5**        BDOS*
  462. ABORT           ZZFIO**         ZZBUF**
  463.  
  464.  
  465. *    indicates a non standard function
  466.  
  467. **    indicates a system function 
  468.  
  469.  
  470. SYSTEM MODULES
  471.  
  472. Refer  to  the  source files of these modules  for  more  details 
  473. regarding operation.
  474.  
  475. ULINK  (251 bytes) contains the routines to steer the 'C' program 
  476. from CP/M to the user program and back again to CP/M. This module 
  477. is the only one in the library to have an entry point defined  as 
  478. a starting point, therefore the program will always start here. 
  479.  
  480. CALL1  (32  bytes)  contains  the code to  support  the  multiply 
  481. operator. ( * )
  482.  
  483. CALL2  (94  bytes)  contains  the  code  to  support  the  divide 
  484. and modulus operators. ( /  % )
  485.  
  486. CALL3  (26  bytes)  contains  the  code  to  support  the  switch 
  487. statement.
  488.  
  489. CALL4 (21 bytes) contains the code to support the right and  left 
  490. shift operators. ( >>  << )
  491.  
  492. CALL5  (235  bytes)  contains  the  code  to  support  all  other 
  493. arithmetic  and  logical operators as well as memory and  address 
  494. fetch and store operations.
  495.  
  496. ZZFIO  (23  bytes) contains storage for global variables used  by 
  497. file I/O and fgetc, fputc, etc . . .
  498.  
  499. ZZBUF  (1 byte) is the last module in the library and  serves  to 
  500. mark  the  starting point for I/O buffers and the dynamic  memory 
  501. allocation scheme.
  502.  
  503.